This article explains how Andrej Karpathy’s simple CLAUDE.md file—just four rules for AI coding agents—sparked a huge surge on GitHub by curbing overconfident, over-engineered AI edits. It shows that the real bottleneck in AI-assisted development isn’t code generation but discipline and predictable behavior.

• Karpathy's 65-line CLAUDE.md file hit #1 on GitHub Trending with 220,000+ stars across mirrors and forks, using just four behavioral rules (think first, avoid speculative abstractions, make surgical changes, define success criteria) rather than any new model or technology.
• Its popularity shows the real bottleneck in AI coding isn't intelligence but judgment and constraint—teams reported fewer hallucinations, cleaner diffs, and fewer broken builds simply by limiting AI overconfidence and scope creep.
• It signals a shift from prompt engineering to "behavioral specs"—developers increasingly focus on specifying how AI should think and scope work rather than just generating code.
• Critics note the rules are generic and can't substitute for real architecture, testing, or human code review.

This article examines how AGENTS.md files impact AI coding agents, showing that well-structured agent docs can boost code quality by up to 15% while poorly designed ones can hurt performance. It outlines seven patterns that work—like progressive disclosure, step-by-step workflows, decision tables, real-code examples, and pairing “don’ts” with “dos”—and warns against overexploration from excessive context or warnings.

• AGENTS.md quality swings are huge: good ones boost output as much as upgrading from Haiku to Opus, bad ones perform worse than having no doc at all.
• Keep it short (100-150 lines) with details pushed to reference docs—bloated files cause "overexploration" where agents burn tens of thousands of tokens on irrelevant context and produce worse results (one case: completeness dropped 25% after the agent read 80K extraneous tokens for a two-line config change).
• Concrete structure wins: numbered step-by-step workflows cut missing files from 40% to 10% (+25% correctness), decision tables boosted best_practices by 25%, and real 3-10 line code snippets raised code_reuse by 20%.
• Always pair "don'ts" with concrete "dos," and scope docs to modular subsystems (~100 files) rather than writing sprawling repo-wide guides.